پیکربندی تایپ‌اسکریپت: تسلط بر گزینه‌های کامپایلر TSConfig

فایل tsconfig.json قلب هر پروژه تایپ‌اسکریپت است. این فایل نحوه تبدیل فایل‌های .ts شما به جاوااسکریپت توسط کامپایلر تایپ‌اسکریپت (tsc) را تعیین می‌کند. یک فایل tsconfig.json با پیکربندی مناسب برای حفظ کیفیت کد، اطمینان از سازگاری در محیط‌های مختلف و بهینه‌سازی فرآیند ساخت، حیاتی است. این راهنمای جامع به بررسی عمیق گزینه‌های پیشرفته tsconfig.json می‌پردازد و شما را قادر می‌سازد تا پروژه‌های تایپ‌اسکریپت خود را برای دستیابی به بالاترین عملکرد و قابلیت نگهداری تنظیم کنید.

درک مبانی: چرا TSConfig اهمیت دارد

قبل از اینکه به گزینه‌های پیشرفته بپردازیم، بیایید مرور کنیم که چرا tsconfig.json اینقدر مهم است:

• کنترل کامپایل: این فایل مشخص می‌کند که کدام فایل‌ها باید در پروژه شما گنجانده شوند و چگونه باید کامپایل شوند.
• بررسی نوع (Type Checking): قوانین و دقت بررسی نوع را تعریف می‌کند و به شما کمک می‌کند تا خطاها را در مراحل اولیه چرخه توسعه شناسایی کنید.
• کنترل خروجی: نسخه جاوااسکریپت هدف، سیستم ماژول و دایرکتوری خروجی را تعیین می‌کند.
• یکپارچه‌سازی با IDE: اطلاعات ارزشمندی را برای IDEها (مانند VS Code، WebStorm و غیره) برای ویژگی‌هایی مانند تکمیل خودکار کد، برجسته‌سازی خطاها و بازآرایی کد (refactoring) فراهم می‌کند.

بدون فایل tsconfig.json، کامپایلر تایپ‌اسکریپت از تنظیمات پیش‌فرض استفاده می‌کند که ممکن است برای همه پروژه‌ها مناسب نباشد. این می‌تواند منجر به رفتار غیرمنتظره، مشکلات سازگاری و تجربه توسعه نامطلوب شود.

ایجاد TSConfig شما: شروع سریع

برای ایجاد یک فایل tsconfig.json، کافی است دستور زیر را در دایرکتوری ریشه پروژه خود اجرا کنید:

            tsc --init
            

              
                Copy
              
            
          

این دستور یک فایل tsconfig.json پایه با برخی گزینه‌های رایج ایجاد می‌کند. سپس می‌توانید این فایل را برای پاسخگویی به نیازهای خاص پروژه خود سفارشی کنید.

گزینه‌های کلیدی کامپایلر: یک نمای کلی دقیق

فایل tsconfig.json حاوی یک شیء compilerOptions است که در آن کامپایلر تایپ‌اسکریپت را پیکربندی می‌کنید. بیایید برخی از مهم‌ترین و پرکاربردترین گزینه‌ها را بررسی کنیم:

target

این گزینه نسخه هدف ECMAScript را برای کد جاوااسکریپت کامپایل‌شده مشخص می‌کند. این تعیین می‌کند که کامپایلر از کدام ویژگی‌های جاوااسکریپت استفاده کند و سازگاری با محیط هدف (مانند مرورگرها، Node.js) را تضمین می‌کند. مقادیر رایج شامل ES5، ES6 (ES2015)، ES2017، ES2018، ES2019، ES2020، ES2021، ES2022، ESNext است. استفاده از ESNext جدیدترین ویژگی‌های پشتیبانی شده ECMAScript را هدف قرار می‌دهد.

مثال:

            "compilerOptions": {
  "target": "ES2020"
}
            

              
                Copy
              
            
          

این پیکربندی به کامپایلر دستور می‌دهد تا کد جاوااسکریپت سازگار با ECMAScript 2020 تولید کند.

module

این گزینه سیستم ماژول مورد استفاده در کد جاوااسکریپت کامپایل‌شده را مشخص می‌کند. مقادیر رایج شامل CommonJS، AMD، System، UMD، ES6 (ES2015)، ES2020 و ESNext است. انتخاب سیستم ماژول به محیط هدف و بارگذارنده ماژول مورد استفاده (مانند Node.js، Webpack، Browserify) بستگی دارد.

مثال:

            "compilerOptions": {
  "module": "CommonJS"
}
            

              
                Copy
              
            
          

این پیکربندی برای پروژه‌های Node.js که معمولاً از سیستم ماژول CommonJS استفاده می‌کنند، مناسب است.

lib

این گزینه مجموعه‌ای از فایل‌های کتابخانه‌ای را مشخص می‌کند که در فرآیند کامپایل گنجانده می‌شوند. این فایل‌های کتابخانه‌ای تعاریف نوع (type definitions) را برای APIهای داخلی جاوااسکریپت و APIهای مرورگر فراهم می‌کنند. مقادیر رایج شامل ES5، ES6، ES7، DOM، WebWorker، ScriptHost و موارد دیگر است.

مثال:

            "compilerOptions": {
  "lib": ["ES2020", "DOM"]
}
            

              
                Copy
              
            
          

این پیکربندی شامل تعاریف نوع برای ECMAScript 2020 و DOM API است که برای پروژه‌های مبتنی بر مرورگر ضروری است.

allowJs

این گزینه به کامپایلر تایپ‌اسکریپت اجازه می‌دهد تا فایل‌های جاوااسکریپت را در کنار فایل‌های تایپ‌اسکریپت کامپایل کند. این می‌تواند هنگام مهاجرت یک پروژه جاوااسکریپت به تایپ‌اسکریپت یا هنگام کار با کدهای جاوااسکریپت موجود مفید باشد.

مثال:

            "compilerOptions": {
  "allowJs": true
}
            

              
                Copy
              
            
          

با فعال بودن این گزینه، کامپایلر هم فایل‌های .ts و هم .js را پردازش می‌کند.

checkJs

این گزینه بررسی نوع را برای فایل‌های جاوااسکریپت فعال می‌کند. هنگامی که با allowJs ترکیب شود، به تایپ‌اسکریپت اجازه می‌دهد تا خطاهای نوع بالقوه را در کد جاوااسکریپت شما شناسایی کند.

مثال:

            "compilerOptions": {
  "allowJs": true,
  "checkJs": true
}
            

              
                Copy
              
            
          

این پیکربندی بررسی نوع را هم برای فایل‌های تایپ‌اسکریپت و هم جاوااسکریپت فراهم می‌کند.

jsx

این گزینه نحوه تبدیل سینتکس JSX (که در React و سایر فریم‌ورک‌ها استفاده می‌شود) را مشخص می‌کند. مقادیر رایج شامل preserve، react، react-native و react-jsx است. preserve سینتکس JSX را به همان شکل باقی می‌گذارد، react آن را به فراخوانی‌های React.createElement تبدیل می‌کند، react-native برای توسعه React Native است، و react-jsx آن را به توابع فکتوری JSX تبدیل می‌کند. react-jsxdev برای اهداف توسعه است.

مثال:

            "compilerOptions": {
  "jsx": "react"
}
            

              
                Copy
              
            
          

این پیکربندی برای پروژه‌های React مناسب است و JSX را به فراخوانی‌های React.createElement تبدیل می‌کند.

declaration

این گزینه فایل‌های اعلان (.d.ts) را برای کد تایپ‌اسکریپت شما تولید می‌کند. فایل‌های اعلان اطلاعات نوع را برای کد شما فراهم می‌کنند و به پروژه‌های دیگر تایپ‌اسکریپت یا جاوااسکریپت اجازه می‌دهند تا از کد شما با بررسی نوع مناسب استفاده کنند.

مثال:

            "compilerOptions": {
  "declaration": true
}
            

              
                Copy
              
            
          

این پیکربندی فایل‌های .d.ts را در کنار فایل‌های جاوااسکریپت کامپایل‌شده تولید می‌کند.

declarationMap

این گزینه فایل‌های سورس مپ (.d.ts.map) را برای فایل‌های اعلان تولید شده ایجاد می‌کند. سورس مپ‌ها به دیباگرها و ابزارهای دیگر اجازه می‌دهند تا هنگام کار با فایل‌های اعلان، به کد منبع اصلی تایپ‌اسکریپت بازگردند.

مثال:

            "compilerOptions": {
  "declaration": true,
  "declarationMap": true
}
            

              
                Copy
              
            
          

sourceMap

این گزینه فایل‌های سورس مپ (.js.map) را برای کد جاوااسکریپت کامپایل‌شده تولید می‌کند. سورس مپ‌ها به دیباگرها و ابزارهای دیگر اجازه می‌دهند تا هنگام دیباگ کردن در مرورگر یا محیط‌های دیگر، به کد منبع اصلی تایپ‌اسکریپت بازگردند.

مثال:

            "compilerOptions": {
  "sourceMap": true
}
            

              
                Copy
              
            
          

outFile

این گزینه تمام فایل‌های خروجی را به هم متصل کرده و در یک فایل واحد منتشر می‌کند. این معمولاً برای بسته‌بندی کد برای برنامه‌های مبتنی بر مرورگر استفاده می‌شود.

مثال:

            "compilerOptions": {
  "outFile": "dist/bundle.js"
}
            

              
                Copy
              
            
          

outDir

این گزینه دایرکتوری خروجی را برای فایل‌های جاوااسکریپت کامپایل‌شده مشخص می‌کند. اگر مشخص نشود، کامپایلر فایل‌های خروجی را در همان دایرکتوری فایل‌های منبع قرار می‌دهد.

مثال:

            "compilerOptions": {
  "outDir": "dist"
}
            

              
                Copy
              
            
          

این پیکربندی فایل‌های جاوااسکریپت کامپایل‌شده را در دایرکتوری dist قرار می‌دهد.

rootDir

این گزینه دایرکتوری ریشه پروژه تایپ‌اسکریپت را مشخص می‌کند. کامپایلر از این دایرکتوری برای حل نام‌های ماژول و تولید مسیرهای فایل خروجی استفاده می‌کند. این به ویژه برای ساختارهای پیچیده پروژه مفید است.

مثال:

            "compilerOptions": {
  "rootDir": "src"
}
            

              
                Copy
              
            
          

removeComments

این گزینه کامنت‌ها را از کد جاوااسکریپت کامپایل‌شده حذف می‌کند. این می‌تواند به کاهش حجم فایل‌های خروجی کمک کند.

مثال:

            "compilerOptions": {
  "removeComments": true
}
            

              
                Copy
              
            
          

noEmitOnError

این گزینه از تولید فایل‌های جاوااسکریپت توسط کامپایلر در صورت شناسایی هرگونه خطای نوع جلوگیری می‌کند. این تضمین می‌کند که فقط کد معتبر تولید می‌شود.

مثال:

            "compilerOptions": {
  "noEmitOnError": true
}
            

              
                Copy
              
            
          

strict

این گزینه تمام گزینه‌های بررسی نوع سخت‌گیرانه را فعال می‌کند. این برای پروژه‌های جدید بسیار توصیه می‌شود زیرا به شناسایی خطاهای بالقوه و اجرای بهترین شیوه‌ها کمک می‌کند.

مثال:

            "compilerOptions": {
  "strict": true
}
            

              
                Copy
              
            
          

فعال کردن حالت strict معادل فعال کردن گزینه‌های زیر است:

• noImplicitAny
• noImplicitThis
• alwaysStrict
• strictNullChecks
• strictFunctionTypes
• strictBindCallApply
• noImplicitReturns
• noFallthroughCasesInSwitch

esModuleInterop

این گزینه قابلیت همکاری بین ماژول‌های CommonJS و ES را فعال می‌کند. این به شما امکان می‌دهد ماژول‌های CommonJS را در ماژول‌های ES وارد کنید و بالعکس.

مثال:

            "compilerOptions": {
  "esModuleInterop": true
}
            

              
                Copy
              
            
          

forceConsistentCasingInFileNames

این گزینه استفاده از حروف با اندازه یکسان در نام فایل‌ها را اعمال می‌کند. این برای سازگاری بین پلتفرم‌ها مهم است، زیرا برخی از سیستم‌عامل‌ها به حروف بزرگ و کوچک حساس هستند در حالی که برخی دیگر نیستند.

مثال:

            "compilerOptions": {
  "forceConsistentCasingInFileNames": true
}
            

              
                Copy
              
            
          

baseUrl و paths

این گزینه‌ها به شما امکان می‌دهند تا تفکیک ماژول (module resolution) را پیکربندی کنید. baseUrl دایرکتوری پایه را برای تفکیک نام‌های ماژول غیرنسبی مشخص می‌کند و paths به شما اجازه می‌دهد تا نام‌های مستعار (alias) سفارشی برای ماژول‌ها تعریف کنید.

مثال:

            "compilerOptions": {
  "baseUrl": ".",
  "paths": {
    "@components/*": ["src/components/*"],
    "@utils/*": ["src/utils/*"]
  }
}
            

              
                Copy
              
            
          

این پیکربندی به شما امکان می‌دهد ماژول‌ها را با استفاده از نام‌های مستعار مانند @components/MyComponent و @utils/myFunction وارد کنید.

پیکربندی پیشرفته: فراتر از مبانی

اکنون، بیایید برخی از گزینه‌های پیشرفته tsconfig.json را بررسی کنیم که می‌توانند تجربه توسعه تایپ‌اسکریپت شما را بیشتر بهبود بخشند.

کامپایل افزایشی (Incremental Compilation)

تایپ‌اسکریپت از کامپایل افزایشی پشتیبانی می‌کند که می‌تواند به طور قابل توجهی سرعت فرآیند ساخت را برای پروژه‌های بزرگ افزایش دهد. برای فعال کردن کامپایل افزایشی، گزینه incremental را روی true تنظیم کرده و یک گزینه tsBuildInfoFile را مشخص کنید.

مثال:

            "compilerOptions": {
  "incremental": true,
  "tsBuildInfoFile": ".tsbuildinfo"
}
            

              
                Copy
              
            
          

گزینه tsBuildInfoFile فایلی را مشخص می‌کند که کامپایلر اطلاعات ساخت را در آن ذخیره می‌کند. این اطلاعات برای تعیین اینکه کدام فایل‌ها در ساخت‌های بعدی نیاز به کامپایل مجدد دارند، استفاده می‌شود.

ارجاعات پروژه (Project References)

ارجاعات پروژه به شما امکان می‌دهند کد خود را به پروژه‌های کوچک‌تر و قابل مدیریت‌تر تقسیم کنید. این می‌تواند زمان ساخت و سازماندهی کد را برای پایگاه‌های کد بزرگ بهبود بخشد. یک تشبیه خوب برای این مفهوم، معماری میکروسرویس است - هر سرویس مستقل است، اما به دیگران در اکوسیستم تکیه می‌کند.

برای استفاده از ارجاعات پروژه، باید برای هر پروژه یک فایل tsconfig.json جداگانه ایجاد کنید. سپس، در فایل tsconfig.json اصلی، می‌توانید پروژه‌هایی را که باید ارجاع داده شوند با استفاده از گزینه references مشخص کنید.

مثال:

            {
  "compilerOptions": {
    ...
  },
  "references": [
    { "path": "./project1" },
    { "path": "./project2" }
  ]
}
            

              
                Copy
              
            
          

این پیکربندی مشخص می‌کند که پروژه فعلی به پروژه‌های واقع در دایرکتوری‌های ./project1 و ./project2 وابسته است.

تبدیل‌کننده‌های سفارشی (Custom Transformers)

تبدیل‌کننده‌های سفارشی به شما امکان می‌دهند خروجی کامپایلر تایپ‌اسکریپت را تغییر دهید. این می‌تواند برای اهداف مختلفی مانند افزودن تبدیل‌های کد سفارشی، حذف کد استفاده نشده یا بهینه‌سازی خروجی برای محیط‌های خاص استفاده شود. آنها معمولاً برای وظایف بین‌المللی‌سازی (i18n) و بومی‌سازی استفاده می‌شوند.

برای استفاده از تبدیل‌کننده‌های سفارشی، باید یک فایل جاوااسکریپت جداگانه ایجاد کنید که یک تابع را صادر (export) می‌کند که توسط کامپایلر فراخوانی می‌شود. سپس، می‌توانید فایل تبدیل‌کننده را با استفاده از گزینه plugins در فایل tsconfig.json مشخص کنید.

مثال:

            {
  "compilerOptions": {
    ...
    "plugins": [
      { "transform": "./transformer.js" }
    ]
  }
}
            

              
                Copy
              
            
          

این پیکربندی مشخص می‌کند که فایل ./transformer.js باید به عنوان یک تبدیل‌کننده سفارشی استفاده شود.

Files، Include و Exclude

علاوه بر compilerOptions، سایر گزینه‌های سطح ریشه در tsconfig.json کنترل می‌کنند که کدام فایل‌ها در فرآیند کامپایل گنجانده شوند:

• files: آرایه‌ای از مسیرهای فایل برای گنجاندن در کامپایل.
• include: آرایه‌ای از الگوهای glob که فایل‌های مورد نظر برای گنجاندن را مشخص می‌کند.
• exclude: آرایه‌ای از الگوهای glob که فایل‌های مورد نظر برای حذف را مشخص می‌کند.

این گزینه‌ها کنترل دقیقی بر روی اینکه کدام فایل‌ها توسط کامپایلر تایپ‌اسکریپت پردازش می‌شوند، فراهم می‌کنند. به عنوان مثال، می‌توانید فایل‌های تست یا کدهای تولید شده را از فرآیند کامپایل حذف کنید.

مثال:

            {
  "compilerOptions": { ... },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
}
            

              
                Copy
              
            
          

این پیکربندی تمام فایل‌های موجود در دایرکتوری src و زیرشاخه‌های آن را شامل می‌شود، در حالی که فایل‌های موجود در دایرکتوری‌های node_modules و dist و همچنین هر فایلی با پسوند .spec.ts (که معمولاً برای تست‌های واحد استفاده می‌شود) را حذف می‌کند.

گزینه‌های کامپایلر برای سناریوهای خاص

پروژه‌های مختلف ممکن است برای دستیابی به نتایج بهینه به تنظیمات کامپایلر متفاوتی نیاز داشته باشند. بیایید به چند سناریوی خاص و تنظیمات کامپایلر توصیه شده برای هر کدام نگاهی بیندازیم.

توسعه برنامه‌های وب

برای توسعه برنامه‌های وب، معمولاً می‌خواهید از تنظیمات کامپایلر زیر استفاده کنید:

            {
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Node",
    "jsx": "react-jsx",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "sourceMap": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
            

              
                Copy
              
            
          

این تنظیمات برای برنامه‌های وب مدرن با استفاده از React یا سایر فریم‌ورک‌های مشابه مناسب است. آنها جدیدترین ویژگی‌های ECMAScript را هدف قرار می‌دهند، از ماژول‌های ES استفاده می‌کنند و بررسی نوع سخت‌گیرانه را فعال می‌کنند.

توسعه بک‌اند با Node.js

برای توسعه بک‌اند با Node.js، معمولاً می‌خواهید از تنظیمات کامپایلر زیر استفاده کنید:

            {
  "compilerOptions": {
    "target": "ESNext",
    "module": "CommonJS",
    "esModuleInterop": true,
    "strict": true,
    "sourceMap": true,
    "outDir": "dist",
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
            

              
                Copy
              
            
          

این تنظیمات برای برنامه‌های Node.js که از سیستم ماژول CommonJS استفاده می‌کنند مناسب است. آنها جدیدترین ویژگی‌های ECMAScript را هدف قرار می‌دهند، بررسی نوع سخت‌گیرانه را فعال می‌کنند و به شما امکان می‌دهند فایل‌های JSON را به عنوان ماژول وارد کنید.

توسعه کتابخانه

برای توسعه کتابخانه، معمولاً می‌خواهید از تنظیمات کامپایلر زیر استفاده کنید:

            {
  "compilerOptions": {
    "target": "ES5",
    "module": "UMD",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}
            

              
                Copy
              
            
          

این تنظیمات برای ایجاد کتابخانه‌هایی مناسب است که می‌توانند هم در محیط مرورگر و هم در Node.js استفاده شوند. آنها فایل‌های اعلان و سورس مپ‌ها را برای تجربه توسعه‌دهنده بهتر تولید می‌کنند.

بهترین شیوه‌ها برای مدیریت TSConfig

در اینجا چند روش برتر برای مدیریت فایل‌های tsconfig.json شما آورده شده است:

• با یک پیکربندی پایه شروع کنید: یک فایل tsconfig.json پایه با تنظیمات مشترک ایجاد کنید و سپس آن را در پروژه‌های دیگر با استفاده از گزینه extends گسترش دهید.
• از حالت strict استفاده کنید: حالت strict را فعال کنید تا خطاهای بالقوه را شناسایی کرده و بهترین شیوه‌ها را اجرا کنید.
• تفکیک ماژول را پیکربندی کنید: تفکیک ماژول را به درستی پیکربندی کنید تا از خطاهای import جلوگیری کنید.
• از ارجاعات پروژه استفاده کنید: کد خود را با استفاده از ارجاعات پروژه به پروژه‌های کوچک‌تر و قابل مدیریت‌تر تقسیم کنید.
• فایل tsconfig.json خود را به‌روز نگه دارید: فایل tsconfig.json خود را به طور منظم مرور کرده و با تکامل پروژه آن را به‌روز کنید.
• فایل tsconfig.json خود را در کنترل نسخه قرار دهید: فایل tsconfig.json خود را به همراه سایر کدهای منبع به کنترل نسخه بسپارید.
• پیکربندی خود را مستند کنید: کامنت‌هایی به فایل tsconfig.json خود اضافه کنید تا هدف هر گزینه را توضیح دهید.

نتیجه‌گیری: تسلط بر پیکربندی تایپ‌اسکریپت

فایل tsconfig.json ابزاری قدرتمند برای پیکربندی کامپایلر تایپ‌اسکریپت و کنترل فرآیند ساخت است. با درک گزینه‌های موجود و پیروی از بهترین شیوه‌ها، می‌توانید پروژه‌های تایپ‌اسکریپت خود را برای عملکرد، قابلیت نگهداری و سازگاری بهینه تنظیم کنید. این راهنما یک نمای کلی جامع از گزینه‌های پیشرفته موجود در فایل tsconfig.json ارائه داده است و شما را قادر می‌سازد تا کنترل کامل بر گردش کار توسعه تایپ‌اسکریپت خود داشته باشید. به یاد داشته باشید که همیشه برای به‌روزترین اطلاعات و راهنمایی‌ها به مستندات رسمی تایپ‌اسکریپت مراجعه کنید. با تکامل پروژه‌های شما، درک و استفاده شما از این ابزارهای پیکربندی قدرتمند نیز باید تکامل یابد. کدنویسی خوبی داشته باشید!